/*
 * PermissionRequest.java
 * 
 * Created on Sep 19, 2007, 4:59:56 PM
 * 
 * To change this template, choose Tools | Templates
 * and open the template in the editor.
 */

package org.glossitope.desklet.services;

/**
 * Allows widgets to check and request permissions.  Currently the only supported permission is of type 
 * <b>http</b>.  
 * 
 * <ul>
 *  <li><b>http</b> parameters are:
 *    <ul>
 *      <li><i>domain</i> as a String</li>
 *    </ul>
 *    example: <code>isGranted("http",new String[]{"myserver.com"},"to check stuff at my server");</code>
 *  </li>
 * </ul>
 * 
 * @author joshua@marinacci.org
 */
public abstract class PermissionRequest {
    
    /**
     * Check if permission has already been granted for the specified permission
     * <b>NOTE:</b> this method must be called from the Event Dispatch Thread. An exception will be thrown otherwise.
     * 
     * @param permissionType a string representing the kind of permission. Currently only
     * "http" is supported.
     * 
     * @param parameters an array of objects representing the parameters for this type of
     * permission. For 'http' the array should be an array of strings, with only one string for
     * the domain to connect to. ex: new String[]{"myserver.com"}.
     * 
     * @param description a description of what this widget wants to request this permisson. For example,
     * the description of an 'http' request to 'weather.gov' might be "to check the weather"
     * 
     * @return if permission has already been approved
     * 
     */
    public abstract boolean isAlreadyApproved(String permissionType, Object[] parameters, String description);
    
    
    /**
     * Request approval for the specified permission. The user will be shown a special dialog to approve
     * or deny the permission request.
     * 
     * <b>NOTE:</b> this method must be called from the Event Dispatch Thread. An exception will be thrown otherwise.
     * 
     * @param permissionType a string representing the kind of permission. Currently only
     * "http" is supported.
     * 
     * @param parameters an array of objects representing the parameters for this type of
     * permission. For 'http' the array should be an array of strings, with only one string for
     * the domain to connect to. ex: new String[]{"myserver.com"}.
     * 
     * @param description a description of what this widget wants to request this permisson. For example,
     * the description of an 'http' request to 'weather.gov' might be "to check the weather"
     * 
     * @return if permission was approved
     * 
     */
    public abstract boolean requestPermission(String permissionType, Object[] parameters, String description);
}
